#+TITLE: org-roam-search readme

* org-roam-search

[[https://www.orgroam.com/][org-roam]] is great, but the basic searching functions leave much to be desired.

This hacky bit of elisp allows you to search through your org-roam database, for text strings/regexp /within/ your org-roam nodes.

All results are displayed in a separate buffer, with links to open what you are looking for directly.

* Installation

For now, the simplest way to add this to your install is to clone this repo, and place the following into you emacs config:-
#+BEGIN_SRC org
(load-file "/path/to/org-roam-search.el")
#+END_SRC
Be sure to put in the correct path for where your copy of ~org-roam-search.el~ is saved.

If you are doing any hacking on the main org file, another option is:-
#+BEGIN_SRC org
(org-babel-load-file "/path/to/org-roam-search.org")
#+END_SRC
to have it automatically tangled and loaded on startup.


* Usage

~org-roam-search~ can be launched interactively, it will ask you for your search term in the mini buffer then display all results in a separate buffer.

The required search can also be passed as an argument from other elisp:-
#+BEGIN_SRC
(org-roam-search "just a test")
#+END_SRC

If no results are found, a message will appear in the mini-buffer and the search results buffer will not open.

* Dependencies

The main logic of this function relies on calls to the shell commands ~grep~ and ~cut~ - beyond that it is basic elisp. It /should/ work fine on the following operating systems:-

- Linux (tested)
- Android, running Emacs in Termux (tested)
- The various BSDs
- MacOS
- Windows running Emacs via WSL

Any more esoteric systems /might/ work, but I have neither the means nor the motivation to test if these are supported.


And it should go without saying, that a properly setup ~org-roam~ environment needs to be in place!

* Changelog

- v0.1 - Initial release

* Hacking

If you plan to hack on this at all, please mmake any code changes in the ~org-roam-search.org~ file, and tangle that to the ~org-roam-search.el~ file.

Feel free to send pull requests etc, I'm sure there are many stupid things I've done here that have better ways of being implemented, I'm still finding my feet with elisp (and lisp in general!)
  
* Licensing

~org-roam-search~ is licensed under the GPLv2, see included LICENSE file for details.
